POST /api/rooms/{roomID}/message

Send a message to the AI assistant and receive a response

Sends a user message to the Duet AI assistant for a specific room. The assistant maintains conversation history and can execute sandboxed commands using <run> tags.

Endpoint

POST /api/rooms/{roomID}/message

Path Parameters

roomID · string · required

Unique identifier for the conversation room. Used to maintain isolated conversation state and sandbox environments.

Request Body

text · string · required

The user’s message text. Must be at least 1 character long.

text: z.string().min(1, "Text cannot be empty")

userId · string

Optional identifier for the user sending the message. Used to track message authorship in multi-user scenarios.

Response

reply · string

The AI assistant’s response text. May include command outputs if the assistant executed sandbox commands.

messages · DuetMessage[]

The complete conversation history for this room (last 50 messages). Each message includes:

Show DuetMessage Schema

role · 'user' | 'agent'

The message sender type

userId · string

User identifier (only present for user messages)

text · string

The message content

ts · number

Unix timestamp in milliseconds

AI Behavior

The assistant uses the @cf/meta/llama-3-8b-instruct model with the following system prompt:

“You are Duet, a concise pair-programming assistant. You can run commands in a sandbox using <run>command</run> tags. When asked to perform an action, briefly explain what you will do and wrap the exact shell command(s) in <run> tags. Do NOT include predicted output in your response - just provide the explanation and command.”

The assistant automatically executes commands wrapped in <run> tags and appends output to the response.

Example Request

curl -X POST https://your-worker.workers.dev/api/rooms/room-123/message \
  -H "Content-Type: application/json" \
  -d '{
    "text": "List all files in the current directory",
    "userId": "user-456"
  }'

Example Response

{
  "reply": "I'll list the files in the current directory.\n\nOutput (ls -la):\ntotal 12\ndrwxr-xr-x 2 user user 4096 Mar 1 10:30 .\ndrwxr-xr-x 3 user user 4096 Mar 1 10:29 ..\n-rw-r--r-- 1 user user  128 Mar 1 10:30 example.txt",
  "messages": [
    {
      "role": "user",
      "userId": "user-456",
      "text": "List all files in the current directory",
      "ts": 1709287800000
    },
    {
      "role": "agent",
      "text": "I'll list the files in the current directory.\n\nOutput (ls -la):\n...",
      "ts": 1709287801500
    }
  ]
}

Error Responses

400 Bad Request

Returned when request validation fails:

{
  "error": "invalid request",
  "details": {
    "text": ["Text cannot be empty"]
  }
}

404 Not Found

Returned when the room ID is missing from the URL path.

405 Method Not Allowed

Returned when using a method other than POST.

Implementation Details

• Conversation history is limited to the last 10 messages when calling the AI model (cf-worker/index.ts:164)
• Total message history stored per room: 50 messages (cf-worker/index.ts:179)
• Command output is truncated to 500 characters (cf-worker/index.ts:200)
• Sandbox instances are isolated per room using naming pattern: sandbox-{roomID} (cf-worker/index.ts:196)

Related Endpoints

• POST /api/rooms//sandbox/exec - Execute commands directly without AI
• DELETE /api/rooms/ - Clean up room resources